Revit API · Referenz

Cheatsheet:
Familien

Kompakte Referenz für die Arbeit mit Familien in der Revit API – Laden, Erstellen, Platzieren und Parameter verwalten in C# und Python.

C# / .NET Python / pyRevit
Zurück zur BIM-Werkzeugkiste
Family family = doc.LoadFamily("Tür.rfa");
// FamilySymbol aktivieren
symbol.Activate(); // wichtig!
doc.Create.NewFamilyInstance(xyz, symbol …)

Grundlagen: Familien in der Revit API

Familien in Revit sind wiederverwendbare Elemente wie Türen, Fenster oder Möbel. Die Revit API bietet umfangreiche Möglichkeiten, Familien zu laden, erstellen, bearbeiten und verwalten.

Hierarchie merken: Family → FamilySymbol (Typ) → FamilyInstance (Instanz im Projekt)

Wichtige Klassen & Namespaces

Klasse / Objekt Beschreibung Namespace
Family Repräsentiert eine Familie im Projekt oder in der Bibliothek. Autodesk.Revit.DB
FamilySymbol Ein Typ innerhalb einer Familie (z. B. eine bestimmte Türgröße). Autodesk.Revit.DB
FamilyInstance Eine Instanz einer Familie im Projekt (z. B. eine Tür in einer Wand). Autodesk.Revit.DB
IFamilyLoadOptions Interface für das Laden von Familien mit benutzerdefinierten Optionen. Autodesk.Revit.DB
Document Das aktuelle Revit-Dokument – Ausgangspunkt aller API-Operationen. Autodesk.Revit.DB
FilteredElementCollector Effiziente Abfrage aller Elemente eines bestimmten Typs im Dokument. Autodesk.Revit.DB

Familien laden und verwalten

Versionskompatibilität: Stelle sicher, dass die RFA-Datei mit der eingesetzten Revit-Version kompatibel ist!

Familie aus einer RFA-Datei laden

C#

C# — Familie laden 
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;

public void LoadFamily(Document doc, string familyPath)
{
    // Familie aus RFA-Datei laden
    Family family;
    doc.LoadFamily(familyPath, out family);

    if (family != null)
    {
        TaskDialog.Show("Erfolg", "Familie geladen: " + family.Name);
    }
}

Python (pyRevit / RPS)

Python — Familie laden 
family_path = "C:/Familien/Tür.rfa"
family = doc.LoadFamily(family_path)
if family:
    print("Familie geladen:", family.Name)

Familie mit benutzerdefinierten Optionen laden

Verwende IFamilyLoadOptions, um das Verhalten beim Laden zu steuern – z. B. ob vorhandene Parameter überschrieben werden sollen.

C#

C# — IFamilyLoadOptions 
public class FamilyLoadOptions : IFamilyLoadOptions
{
    public bool OnFamilyFound(bool familyInUse, out bool overwriteParameterValues)
    {
        overwriteParameterValues = true;
        return true;
    }

    public bool OnSharedFamilyFound(bool familyInUse, out bool overwriteParameterValues)
    {
        overwriteParameterValues = true;
        return true;
    }
}

// Verwendung:
doc.LoadFamily(familyPath, new FamilyLoadOptions(), out Family family);
Python-Einschränkung: IFamilyLoadOptions ist in Python nicht direkt implementierbar. Für diesen Anwendungsfall ist ein C#-Add-In oder Dynamo erforderlich.

Familien erstellen

Das Erstellen neuer Familien erfolgt meist über die Revit-Benutzeroberfläche. Die API kann verwendet werden, um leere Familien zu erstellen oder bestehende Familien programmatisch zu modifizieren.

Leere Familie erstellen

C#

C# — Neue Familie anlegen 
using (Transaction t = new Transaction(doc, "Neue Familie"))
{
    t.Start();

    // Neue Familie erstellen
    Family family = new Family();
    doc.Create.NewFamily(doc, family);

    // Familie als RFA speichern
    string familyPath = "C:/Familien/Neue_Familie.rfa";
    doc.SaveFamily(familyPath);

    t.Commit();
}
Python-Einschränkung: Das direkte Erstellen von Familien über die Python-API ist nicht möglich. Verwende stattdessen Dynamo oder ein C#-Add-In.

Familieninstanzen platzieren

Eine Familieninstanz ist eine konkrete Platzierung einer Familie im Projekt. Bevor eine Instanz erstellt werden kann, muss der FamilySymbol aktiviert werden.

Wichtig: Immer symbol.Activate() vor NewFamilyInstance() aufrufen – sonst folgt eine InvalidOperationException.

Familieninstanz im Projekt platzieren

C#

C# — Instanz platzieren 
public void PlaceFamilyInstance(Document doc, FamilySymbol symbol, XYZ location)
{
    using (Transaction t = new Transaction(doc, "Instanz platzieren"))
    {
        t.Start();

        // Symbol aktivieren – Pflicht!
        if (!symbol.IsActive)
            symbol.Activate();

        FamilyInstance instance = doc.Create.NewFamilyInstance(
            location,
            symbol,
            StructuralType.NonStructural
        );

        t.Commit();
    }
}

Python

Python — Instanz platzieren 
from Autodesk.Revit.DB import XYZ, StructuralType, Transaction

location = XYZ(10, 5, 0)

# Symbol aktivieren
if not symbol.IsActive:
    symbol.Activate()

with Transaction(doc, "Instanz platzieren") as t:
    t.Start()
    instance = doc.Create.NewFamilyInstance(
        location, symbol, StructuralType.NonStructural
    )
    t.Commit()

Familienparameter verwalten

Parameter einer Familieninstanz lesen

C#

C# — Parameter lesen 
public void ReadFamilyParameters(FamilyInstance instance)
{
    foreach (Parameter param in instance.Parameters)
    {
        string name  = param.Definition.Name;
        string value = param.AsValueString() ?? param.AsString();
        TaskDialog.Show("Parameter", $"{name}: {value}");
    }
}

Python

Python — Parameter lesen 
for param in instance.Parameters:
    name  = param.Definition.Name
    value = param.AsValueString() or param.AsString()
    print(f"{name}: {value}")

Parameter einer Familieninstanz ändern

C#

C# — Parameter setzen 
public void SetParameter(Document doc, FamilyInstance instance,
                         string paramName, double newValue)
{
    using (Transaction t = new Transaction(doc, "Parameter ändern"))
    {
        t.Start();

        Parameter param = instance.LookupParameter(paramName);
        if (param != null && !param.IsReadOnly)
            param.Set(newValue);

        t.Commit();
    }
}

Python

Python — Parameter setzen 
from Autodesk.Revit.DB import Transaction

with Transaction(doc, "Parameter setzen") as t:
    t.Start()
    param = instance.LookupParameter("Breite")
    if param and not param.IsReadOnly:
        param.Set(1.2)  # Wert in Fuß (Revit-interne Einheit)
    t.Commit()
Einheitenhinweis: Revit speichert alle Längen intern in Fuß. Beim Setzen von Werten ggf. mit UnitUtils.ConvertToInternalUnits() umrechnen.

Parameter in der UI bearbeiten

Manchmal ist es sinnvoll, Parameter über die Revit-Benutzeroberfläche anzuzeigen oder zur Eingabe aufzufordern. Hierfür bietet die API den TaskDialog sowie das InputBox-Pattern.

Parameter über TaskDialog abfragen (C#)

C# — TaskDialog mit CommandLinks 
using (TaskDialog td = new TaskDialog("Parameter bearbeiten"))
{
    td.MainInstruction = "Welchen Parameter möchtest du ändern?";
    td.MainContent     = "Wähle eine Option aus.";

    td.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "Breite ändern");
    td.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "Höhe ändern");

    TaskDialogResult result = td.Show();

    if (result == TaskDialogResult.CommandLink1)
    {
        // → Breite ändern
    }
    else if (result == TaskDialogResult.CommandLink2)
    {
        // → Höhe ändern
    }
}

Familien im Dokument finden

Alle geladenen Familien im aktuellen Projekt auflisten – nützlich für Export, Qualitätsprüfung oder Batch-Operationen.

Alle Familien auflisten

C#

C# — FilteredElementCollector 
FilteredElementCollector collector = new FilteredElementCollector(doc)
    .OfClass(typeof(Family));

foreach (Family family in collector.Cast<Family>())
{
    // Familientypen auflisten
    foreach (ElementId symbolId in family.GetFamilySymbolIds())
    {
        FamilySymbol sym = doc.GetElement(symbolId) as FamilySymbol;
        TaskDialog.Show("Familie", $"{family.Name} → {sym.Name}");
    }
}

Python

Python — Familien auflisten 
from Autodesk.Revit.DB import FilteredElementCollector, Family

families = FilteredElementCollector(doc).OfClass(Family)

for family in families:
    for sym_id in family.GetFamilySymbolIds():
        sym = doc.GetElement(sym_id)
        print(f"{family.Name} → {sym.Name}")

Familieninstanzen nach Typ suchen

Python — Instanzen eines Typs finden 
from Autodesk.Revit.DB import FilteredElementCollector, FamilyInstance

# Alle FamilyInstances im Modell
instances = FilteredElementCollector(doc)\
    .OfClass(FamilyInstance)\
    .ToElements()

# Nur bestimmten Typ
TARGET = "Einfache Tür"
filtered = [i for i in instances if i.Symbol.FamilyName == TARGET]
print(f"{len(filtered)} Instanzen gefunden")

Häufige Fehler & Lösungen

Fehler / Exception Ursache & Lösung
InvalidOperationException Transaktion nicht gestartet oder nicht korrekt beendet. Immer t.Start() und t.Commit() aufrufen.
ArgumentException Ungültiger Pfad oder Familienname. Pfad auf Existenz prüfen, Sonderzeichen beachten.
ArgumentNullException Übergabe von null-Objekten. Immer Null-Check vor API-Aufrufen einbauen.
FamilySymbol nicht aktiv Vor NewFamilyInstance() immer symbol.Activate() aufrufen.
Familie wird nicht geladen RFA-Datei nicht mit Revit-Version kompatibel. Version prüfen oder in Revit öffnen und neu speichern.
Parameterwert hat keine Wirkung Parameter ist evtl. IsReadOnly == true (formelgesteuert oder gesperrt). Vor Set() immer prüfen.
Falscher Einheitenwert Revit speichert Längen in Fuß. Konvertierung: UnitUtils.ConvertToInternalUnits(wert, UnitTypeId.Meters)

Nützliche Ressourcen

Dokumentation & API-Referenz

GitHub & Community

Kurse & Bücher